home *** CD-ROM | disk | FTP | other *** search
/ isnet Internet / Isnet Internet CD.iso / prog / hiz / 09 / 09.exe / adynware.exe / perl / lib / FileHandle.pm < prev    next >
Encoding:
Perl POD Document  |  1999-12-28  |  6.2 KB  |  239 lines
  1. package FileHandle;
  2.  
  3. use 5.003_11;
  4. use strict;
  5. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
  6.  
  7. $VERSION = "2.00";
  8.  
  9. require IO::File;
  10. @ISA = qw(IO::File);
  11.  
  12. @EXPORT = qw(_IOFBF _IOLBF _IONBF);
  13.  
  14. @EXPORT_OK = qw(
  15.     pipe
  16.  
  17.     autoflush
  18.     output_field_separator
  19.     output_record_separator
  20.     input_record_separator
  21.     input_line_number
  22.     format_page_number
  23.     format_lines_per_page
  24.     format_lines_left
  25.     format_name
  26.     format_top_name
  27.     format_line_break_characters
  28.     format_formfeed
  29.  
  30.     print
  31.     printf
  32.     getline
  33.     getlines
  34. );
  35.  
  36. import IO::Handle grep { !defined(&$_) } @EXPORT, @EXPORT_OK;
  37.  
  38. {
  39.     no strict 'refs';
  40.  
  41.     my %import = (
  42.     'IO::Handle' =>
  43.         [qw(DESTROY new_from_fd fdopen close fileno getc ungetc gets
  44.         eof flush error clearerr setbuf setvbuf _open_mode_string)],
  45.     'IO::Seekable' =>
  46.         [qw(seek tell getpos setpos)],
  47.     'IO::File' =>
  48.         [qw(new new_tmpfile open)]
  49.     );
  50.     for my $pkg (keys %import) {
  51.     for my $func (@{$import{$pkg}}) {
  52.         my $c = *{"${pkg}::$func"}{CODE}
  53.         or die "${pkg}::$func missing";
  54.         *$func = $c;
  55.     }
  56.     }
  57. }
  58.  
  59. sub import {
  60.     my $pkg = shift;
  61.     my $callpkg = caller;
  62.     Exporter::export $pkg, $callpkg, @_;
  63.  
  64.     eval {
  65.     require Fcntl;
  66.     Exporter::export 'Fcntl', $callpkg;
  67.     };
  68. }
  69.  
  70.  
  71. sub pipe {
  72.     my $r = new IO::Handle;
  73.     my $w = new IO::Handle;
  74.     CORE::pipe($r, $w) or return undef;
  75.     ($r, $w);
  76. }
  77.  
  78. bless *STDIN{IO},  "FileHandle" if ref *STDIN{IO}  eq "IO::Handle";
  79. bless *STDOUT{IO}, "FileHandle" if ref *STDOUT{IO} eq "IO::Handle";
  80. bless *STDERR{IO}, "FileHandle" if ref *STDERR{IO} eq "IO::Handle";
  81.  
  82. 1;
  83.  
  84. __END__
  85.  
  86. =head1 NAME
  87.  
  88. FileHandle - supply object methods for filehandles
  89.  
  90. =head1 SYNOPSIS
  91.  
  92.     use FileHandle;
  93.  
  94.     $fh = new FileHandle;
  95.     if ($fh->open "< file") {
  96.         print <$fh>;
  97.         $fh->close;
  98.     }
  99.  
  100.     $fh = new FileHandle "> FOO";
  101.     if (defined $fh) {
  102.         print $fh "bar\n";
  103.         $fh->close;
  104.     }
  105.  
  106.     $fh = new FileHandle "file", "r";
  107.     if (defined $fh) {
  108.         print <$fh>;
  109.         undef $fh;       # automatically closes the file
  110.     }
  111.  
  112.     $fh = new FileHandle "file", O_WRONLY|O_APPEND;
  113.     if (defined $fh) {
  114.         print $fh "corge\n";
  115.         undef $fh;       # automatically closes the file
  116.     }
  117.  
  118.     $pos = $fh->getpos;
  119.     $fh->setpos($pos);
  120.  
  121.     $fh->setvbuf($buffer_var, _IOLBF, 1024);
  122.  
  123.     ($readfh, $writefh) = FileHandle::pipe;
  124.  
  125.     autoflush STDOUT 1;
  126.  
  127. =head1 DESCRIPTION
  128.  
  129. NOTE: This class is now a front-end to the IO::* classes.
  130.  
  131. C<FileHandle::new> creates a C<FileHandle>, which is a reference to a
  132. newly created symbol (see the C<Symbol> package).  If it receives any
  133. parameters, they are passed to C<FileHandle::open>; if the open fails,
  134. the C<FileHandle> object is destroyed.  Otherwise, it is returned to
  135. the caller.
  136.  
  137. C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does.
  138. It requires two parameters, which are passed to C<FileHandle::fdopen>;
  139. if the fdopen fails, the C<FileHandle> object is destroyed.
  140. Otherwise, it is returned to the caller.
  141.  
  142. C<FileHandle::open> accepts one parameter or two.  With one parameter,
  143. it is just a front end for the built-in C<open> function.  With two
  144. parameters, the first parameter is a filename that may include
  145. whitespace or other special characters, and the second parameter is
  146. the open mode, optionally followed by a file permission value.
  147.  
  148. If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.)
  149. or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic
  150. Perl C<open> operator.
  151.  
  152. If C<FileHandle::open> is given a numeric mode, it passes that mode
  153. and the optional permissions value to the Perl C<sysopen> operator.
  154. For convenience, C<FileHandle::import> tries to import the O_XXX
  155. constants from the Fcntl module.  If dynamic loading is not available,
  156. this may fail, but the rest of FileHandle will still work.
  157.  
  158. C<FileHandle::fdopen> is like C<open> except that its first parameter
  159. is not a filename but rather a file handle name, a FileHandle object,
  160. or a file descriptor number.
  161.  
  162. If the C functions fgetpos() and fsetpos() are available, then
  163. C<FileHandle::getpos> returns an opaque value that represents the
  164. current position of the FileHandle, and C<FileHandle::setpos> uses
  165. that value to return to a previously visited position.
  166.  
  167. If the C function setvbuf() is available, then C<FileHandle::setvbuf>
  168. sets the buffering policy for the FileHandle.  The calling sequence
  169. for the Perl function is the same as its C counterpart, including the
  170. macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer
  171. parameter specifies a scalar variable to use as a buffer.  WARNING: A
  172. variable used as a buffer by C<FileHandle::setvbuf> must not be
  173. modified in any way until the FileHandle is closed or until
  174. C<FileHandle::setvbuf> is called again, or memory corruption may
  175. result!
  176.  
  177. See L<perlfunc> for complete descriptions of each of the following
  178. supported C<FileHandle> methods, which are just front ends for the
  179. corresponding built-in functions:
  180.  
  181.     close
  182.     fileno
  183.     getc
  184.     gets
  185.     eof
  186.     clearerr
  187.     seek
  188.     tell
  189.  
  190. See L<perlvar> for complete descriptions of each of the following
  191. supported C<FileHandle> methods:
  192.  
  193.     autoflush
  194.     output_field_separator
  195.     output_record_separator
  196.     input_record_separator
  197.     input_line_number
  198.     format_page_number
  199.     format_lines_per_page
  200.     format_lines_left
  201.     format_name
  202.     format_top_name
  203.     format_line_break_characters
  204.     format_formfeed
  205.  
  206. Furthermore, for doing normal I/O you might need these:
  207.  
  208. =over 
  209.  
  210. =item $fh->print
  211.  
  212. See L<perlfunc/print>.
  213.  
  214. =item $fh->printf
  215.  
  216. See L<perlfunc/printf>.
  217.  
  218. =item $fh->getline
  219.  
  220. This works like <$fh> described in L<perlop/"I/O Operators">
  221. except that it's more readable and can be safely called in an
  222. array context but still returns just one line.
  223.  
  224. =item $fh->getlines
  225.  
  226. This works like <$fh> when called in an array context to
  227. read all the remaining lines in a file, except that it's more readable.
  228. It will also croak() if accidentally called in a scalar context.
  229.  
  230. =back
  231.  
  232. =head1 SEE ALSO
  233.  
  234. The B<IO> extension,
  235. L<perlfunc>, 
  236. L<perlop/"I/O Operators">.
  237.  
  238. =cut
  239.